DLLs can be called from a built Windows application. Shared libraries can be called from Macintosh and Linux applications.

Syntax

[Soft] Declare Sub/Function Name Lib LibraryName [Alias AliasName] ([Parameters]) [As ReturnType]

Notes

Function names for the OS are case sensitive. For example, SetLocalTime works on Win32 but SetlocalTime does not.

Declare statements must not call strictly "classic" libraries like AppearanceLib to run on Mac OS X. If they do not, the application will run in the "classic" environment within Mac OS X.

The Declare statement allows use of constants for Lib names.

When building a Carbon application in the Mach-O format, the Lib parameter to a Declare statement now accepts the name of a system framework in place of a full path to the library. If you wrote a declare against "CoreMIDI", for example, the compiler would see that the Lib string did not contain any path separators, and would expand it to "/System/Library/Frameworks/CoreMIDI.framework/CoreMIDI".

You can pass Nil to a Declare parameter of type Ptr. Passing Nil is not the same as passing a Nil MemoryBlock. The former is a constant and the latter require a conversion operation at run time. If the MemoryBlock is Nil, then the conversion operator will generate a NilObjectException. However, this isn't a problem when passing the constant Nil, as no conversion is needed.

Soft Declares

In versions of REALbasic prior to 2005, the only supported type of declares was a "hard" declare. A hard declare of the form:

tells REALbasic that Foo will always be in Bar, and Bar will always be installed on the user's system. When building your application, REALbasic puts this dependency in your application's Import table. When the system loader tries to load your application, it will automatically find all of these Declares and try to resolve them. If it can't resolve a library or a function from a library, your application would refuse to load and terminate.

The 'Soft" Declare keyword provides some important flexibility. Soft declares are not put into your application's import table so the system loader doesn't try to resolve them. Instead, when you first try to use the softly declared method, REALbasic is responsible for resolving the library and functions. This provides you with a few handy features.

First, it means that you now have a graceful way to deal with the situation of a function or library that isn't found. Instead of your application just not launching, you now have a FunctionNotFound exception that you can catch. Second, REALbasic can be more flexible about loading the library.

For example, LibC on many newer Linux distributions is really a ld loader script that GCC uses to determine which version of LibC to actually link against. This means that you can't write hard declares that link against LibC in REALbasic because libc.so isn't really a symbolic link to the proper shared library (like most other .so files are). You would have to write a Declare against the actual LibC version you wanted, which provides for a very poor experience for users who don't have the same version of LibC installed as you. However, with a soft declare, REALbasic can resolve the loader script for LibC and find the proper shared library to load against In other words, what used to be declared like this:

Can now be declared like this:

With the Soft keyword, you don't have to try to link against a specific version of that library.

On Windows, any function that uses a string will have two different versions, the A version, and the W version. This is the Win32 way of dealing with Unicode. The disadvantage is that the W version of the method is usually available only on Windows NT machines, not 9x ones. If you could not use a Soft declare, you'd have to make two different versions of your application. Using Soft declares, you can do this:

This code runs on any version of Windows. The reason is simple: if the wide char version (W version) is available, then your call will not throw an exception, and because of the WString data type, all your strings will be automatically converted into UTF-16 strings when passed into the function. However, if the call doesn't resolve because you're running on Windows 98 (or another 9x machine), then the exception will be thrown and will use the ANSI (A version) of the function call.

Here is a feature of Soft declares for Macintosh builds. You can call into Mach-O bundles from within a CFM application. For example, if you wanted to use the BSD function called "socket", you can use a soft declare like this:

Checking that a Function is Available

To check whether a function can be resolved, you can use the IsFunctionAvailable function of the System object. It determines whether a function can be resolved without having to actually declare it and try to call into it.

Data Types

The following data types are for use with Declares only:

See the descriptions of each data type for more information.

Automatic Types

There are two new automatic types: WString and CFStringRef. You can pass Nil in place of a CString, WString, CFStringRef, or PString.

You can use these two new types with declares that need a wchar_t * or CFStringRef, respectively. Their usage is the same as with CString, and all data is cleaned up when appropriate. For example:

Examples

Name Conflicts

Suppose you want to write a function that got the various system metrics. You use a method declaration like this:

However, this conflicts with the Win32 API which the function wraps. In this case, you can rename the declare using an alias such as this:

Defining Double-clicks

The following example displays the maximum number of ticks between mouse clicks for two clicks to be considered a "double-click." Above this value, two clicks are considered separate mouse events.

To modify the code to run under Carbon, substitute "CarbonLib" for "InterfaceLib":

The following example gets the current process ID and illustrates Declares for Mach-O, Mac 'classic', Windows, and Linux.

The following example adds the ability to detect a double-click to a Canvas control. The code is placed in a Canvas's MouseUp event handler.

See Also

TargetCarbon, TargetLinux, TargetMacOS, TargetMacOSClassic, TargetMachO, TargetWin32 constants; System object, FunctionNotFound exception; Byte, CFStringRef, CString, OSType, PString, Ptr, Short, UByte, UShort, WindowPtr, WString data types.